home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Cream of the Crop 1
/
Cream of the Crop 1.iso
/
PRINTER
/
PRBGI095.ARJ
/
PRINTBGI.DOC
< prev
next >
Wrap
Text File
|
1992-06-17
|
59KB
|
1,400 lines
Documentation of PRINTBGI package copyright (C) Andrzej Resztak 1991,1992,
all rights reserved.
Introduction
This is a version 0.95 of my PrintBGI toolkit. It was developed to
help programmers using Borland languages (Borland/Turbo C(++)
or Turbo Pascal) and BGI drivers to print graphics on the printer
(and in the future on the other devices) as easy as you can draw it
on the screen. In fact even more, the same function can produce
it's output on a screen or on a printer according to conditions
at which it was called.
It's really easy to learn. Developing your own applications does
not require writing two similar procedures (one for screen drawing
and the other for printer or plotter).
Maintenance of the code is simple, since all extensions or bug fixes
must be made in one place only. I hope you will enjoy this package.
For registration, license and payment see REGISTER.DOC.
This file contains all technical news you must understand to use
this package easy and effectively.
It is quite possibly that this program may not work on your
printer. For example I have never tested it on original IBM printer.
Of course it was tested on some compatible printers but I cannot be
quite sure which command is "compatible" and wich is an enhancment.
So please, let me know if this program does not work with your printer.
My address is given at the end of this file.
SOME OVERVIEW
==============
This package can be divided into two independent parts. First is
BGI driver called by me BItImage BGI driver. This driver can be used
to create bit maps of any size of any picture. (By bit map I mean
two dimensional array of 1,2,4 or 8 bits elements). Note however that
the BGI driver does only some low level work (hardware specific) and
in most cases it depends on high level routines contained in Borland
graphics library kernel. Since there are some differences between printer
and screen oriented devices the initialization of my BitImage BGI
driver is somewhat different of initialization of standard Borland
video BGI drivers. For example it cannot perform any auto detection,
specifying printer being used does not determine the size of the graphic
output and there is some more minor differences. Because of these
differences you must call some PRT_Setxxxxxxx functions of the package to
specify parameters at which you want the BitImage driver to work. And
initialization of the driver should be done using PRT_initgraph function
not standard initgraph routine.
The second part of the package make routines contained in PRTGRAPH library
which hide some of the differences between my BitImage driver and
standard Borland video drivers. They also will make it very easy to print
something on your output device (currently only the dot matrix printers).
Now I describe you the easiest way you can add graphic output
to your programs using this PRINTBGI toolkit. Other sections
will let you know some more features, but this section is very good
for beginning, I hope.
For C users.
First, I highly recommend you to include prototypes of all functions
defined in PRINTBGI package by just inserting
#include <PRTGRAPH.H>
statement at the beginning of your module. Although it is not
necessary I also recommend you to place PRTGRAPH module after any standard
modules you use. It'll enable me some tricky modifications in the future
versions of this package.
You must also remember about linking in PRTGRAPH.LIB either
listing it in PRJ file in integrated environment or adding at the
command line invoking stand alone version of the compiler (or linker).
For Pascal users.
You must list PRTGRAPH unit (among other units you are using) in the
uses clause. You may also list PDrivers unit if you want to use symbolic
constants defined in it.
Although it is not necessary I recommend you to place PRTGRAPH
module after any standard modules you use. It'll enable me some tricky
modifications in the future versions of this package.
Next I assume that you like modular structure programming and have
routine called (say) DrawFunc which meets following conditions.
- It draws on the screen the picture you want to print it out.
- It does not use any nonstandard procedures (that is not
defined in GRAPH.TPU or GRAPHICS.LIB) to manipulate screen
output.
- It does not use initgraph,restorecrtmode,closegraph or setgraphmode
function. It simply assumes that appropriate graphic mode was
established before calling it and will be close down after
it finishes.
- It is written in BGI independent way. That is it uses getmaxx,
getmaxy, getmaxcolor, getaspectratio to get device dependent
characteristic and scales all output according to it.
- If you are using my recommended way to print your picture out, that
is you are using PRT_PrintBGI function then it may happen that this
function will call your drawing routine few or several times to print
out the whole picture. This may happen when there is not enough free
memory to build the whole bit image map of the picture at once. In
that case the bit map will be created piece by piece (each time
calling your drawing routine).
So, although it is not necessary it is recommended that your routine
will draw the same picture (pixel in pixel) each time it will be
called by PRT_PrintBGI function. Of course in the next invoke
of the PRT_PrintBGI routine your DrawFunc may draw something
completely different.
( If it is not your case (you don't have such a function) you may
either rewrite your code to have such a function or use some lower
level functions included in this package. I once again highly
recommend you to choose the first method. )
If you have such a function you must inform the package what kind
of printer you have and at what resolution you want it to operate.
To do that just call PRT_SetDriver function with appropriate parameters
PrinterNo and ModeNo (use constants defined in PRTGRAPH.H or in
PRTGRAPH.PAS) as well as picture size and options.
For example the following statements may print out picture drawn by
DrawFunc on the IBM ProPrinter.
{ /* C version */
int PRTdrv,PRTmode,ReturnCode;
PRT_SetDriver ( IBM9, IBM9_120x72, 4000,3000, PRT_INVERSE );
PRTdrv = DETECT;
PRTmode=0;
/* If you want you may linked in the BitImage BGI driver into the */
/* EXE file. To do so uncomment following two lines. */
/* PRTdrv = PRT_installuserdriver ( "BitImage", NULL ); */
/* PRT_registerfarbgidriver ( &BitImage ); */
ReturnCode = PRT_PrintBGI ( &PRTdrv,&PRTmode,"d:\\bc\\bgi",
DrawFunc, NULL );
}
(* Pascal version *)
var PRTdrv,PRTmode,ReturnCode : integer;
Begin
rc := PRT_SetDriver ( IBM9, IBM9_120x72, 4000,300, 0 or PRT_INVERSE );
{ rc := PRT_SetOutName('file.tst'); }
PRTdrv := DETECT;
PRTmode := 0;
(* If you want you may linked in the BitImage BGI driver into the *)
(* EXE file. To do so uncomment following two lines. *)
{ PRTdrv := PRT_installuserdriver ( 'BitImage', NIL ); }
{ rc := PRT_registerbgidriver ( @BitImage ); }
rc := PRT_PrintBGI ( PRTdrv,PRTmode,'d:\tp\bgi', Draw, nil );
End;
In the best case it's all you have to do. Isn't it easy? I'm sure you
must admit it is.
Of course in most situations it is not enough. Above statements
will cause all output to be sent to the standard PRN device.
If you would like (or have to cause you don't have the printer at
LPT1 for example) to change these parameters you
should call some more functions of the PRINTBGI package as well
as you should code some lines to let user of your program specify
his own requirements. But all of this can be done!
You may also wish to print in inverse, reverse, with any density
at any size. The only disadvantage of using this package is that it
is perceptible slower than usual Print Screen procedures.
========================================================================
FUNCTIONS DETAILS
========================================================================
Following section will describe in details all functions which
can be found in PRINTBGI package. This package as distributed in
shareware version was developed and tested in LARGE and HUGE memory
models (I suppose they are the modes most graphic programs use)
using BC++ v2.0. To use it in other memory model you may need
full sources of it (available from the author - see REGISTER.DOC).
When it is mentioned that the function returns zero on success and
nonzero on failure it means that one of the following codes may be
returned
0 - success.
PRT_NO_MEMORY 1
PRT_WRONG_PARAMETERS 2
PRT_NOT_INITIALIZED 3
PRT_IO_ERROR 4
PRT_ERROR 5
Occasionally you can get other code returned from standard Borland graphic
functions or write procedure. You may also get returned code from your own
DrawFunc routine if it returns nonzero code.
All functions can be divided into following categories.
- Functions used to set various work parameters.
PRT_Buffer
PRT_RescaleFillPattern
PRT_Send
PRT_SetBuffer
PRT_SetOutName
PRT_SetMargins
PRT_SetDriver
PRT_SetViewSize
PRT_SetErrorFunc
PRT_SetOpenFunc
PRT_SetCloseFunc
PRT_SetWriteFunc
PRT_EMSBuffer
PRT_XMSBuffer
setcharsize_Pix
setfillpattern16
- Functions used to print out the picture
PRT_PrintBGI
and some functions used internally by PRT_PrintBGI
(use them only if necessary, the preferable method is using
PRT_PrintBGI which will virtually do all necessary work for you).
PRT_AllocateBuffer
PRT_BuildBitMap
PRT_BufferNeeded
PRT_closegraph
PRT_EndPrt
PRT_FreeBuffer
PRT_getpixel
PRT_initgraph
PRT_InitPrt
PRT_installuserdriver
PRT_PrintBuffer
PRT_registerfarbgidriver
PRT_Unregisterfarbgidriver
- Functions used to get some information about package and current
settings of miscellaneous parameters.
getfillpattern16
PRT_DriverName
PRT_DriverNo
PRT_grapherrormsg
PRT_MaxDriver
PRT_MaxMode
PRT_ModeName
PRT_ModeNo
PRT_Resolution
Global export variable
PRT_HaltPrinting
Here are all functions listed alphabetically. Specification will begin
with function declaration followed by exact description of all parameters.
getfillpattern16
=================
void getfillpattern16 ( char FAR * upattern );
Procedure GetFillPattern16 ( upattern: FillPatternType );
You may use this function to copy 16x16 bit fill pattern set by
setfillpattern16 function into the 32 (!) byte area pointed to by upattern.
This function may be used only when BITIMAGE BGI driver is active, for all
other BGI drivers it will be ignored.
See also PRT_RescaleFillPattern.
PRT_AllocateBuffer
===================
int PRT_AllocateBuffer ( void );
Function PRT_AllocateBuffer: integer;
This function allocates buffer for picture bit image map. It
allocates as much memory as allowed by PRT_SetBuffer but not more than
needed.
Note that attempt to allocate buffer is performed in the
following order. First it is tried to allocate XMS buffer next EMS and
at last conventional one. It may result in allocating buffer smaller
than available memory (e.g if there is 200k of free conventional memory
and 32k of free EMS memory then 32k EMS buffer will be allocated).
Note also that buffer always fits in one kind of memory. There is no
possibility to create buffer say 200K large containing of 60K of
conventional memory and rest of EMS or XMS memory.
Used internally by PRT_PrintBGI may also be called by user needing
some nonstandard possibilities.
Returns 0 on success, nonzero on failure.
see also PRT_SetBuffer, PRT_Buffer, PRT_EMSBuffer, PRT_XMSBuffer,
PRT_BufferNeeded.
PRT_Buffer
=============
int FAR_PROC pascal PRT_Buffer ( void far *address, long size, int usable )
Function PRT_Buffer ( address: pointer; size: longint; usable: integer ):
integer;
Defines conventional memory buffer for use by the PrintBGI package.
Parameters:
usable : 0 (zero) means not to use conventional memory. Other
arguments are in that case ignored (but preferably should
also be zero).
address : Address of conventional memory buffer to use or NULL
(buffer will be allocated later by other functions of
this package).
size : If address is not NULL defines size (in bytes)
of the caller allocated buffer.
If address is NULL than
- positive value defines maximum number of memory
which can be used for the buffer by PrintBGI package.
- negative value defines minimum number of memory left
free after buffer allocation.
- zero allows to allocate as much memory as needed for
the buffer leaving only absolutely minimum free.
Note that allocating buffer larger than 64Kb (to be precise 64KB-16 bytes)
is a little tricky in Turbo Pascal. Althoug I done it in documented way
it might not work in future versions of Turbo Pascal ( that is if heap
memory manager will be changed). I can also give you no guarntee it will
work in all circumstances.
See also PRT_EMSBuffer,PRT_XMSBuffer.
PRT_BufferNeeded
=================
long PRT_BufferNeeded ( int x1, int y1, int x2, int y2 );
Function PRT_BufferNeeded ( x1,y1,x2,y2: integer ): longint;
Returns size of buffer needed to draw picture of specified size on
printer set by PRT_SetDriver. If there exist less free memory than needed
then picture would be drawn in pieces. In that case results of all
functions reading pixel values may be inaccurate.
XMS buffer requires some more memory to build a picture. Use
PRT_XMSBufferNeeded in that case.
May be called only after PRT_SetDriver.
See also PRT_XMSBufferNeeded.
PRT_BuildBitMap
================
int FAR_PROC pascal PRT_BuildBitMap (
int far * graphdriver, int far *graphmode,
const char far *pathtodriver,
int x1,int y1, int x2,int y2,
int ( FAR_PTR * FAR_PROC Draw)(void far* UserPointer),
void far * UserPointer );
Type DrawType = function DrawFunc(UserPointer:pointer) : integer;
Function PRT_BuildBitMap ( var graphdriver,graphmode: integer;
pathtodriver: string;
x1,y1,x2,y2: integer;
DrawFunc : DrawType,
UserPointer: pointer );
Parameters
graphdriver,graphmode,pathtodriver - see PRT_initgraph.
x1,y1,x2,y2 - coordinates of the rectangular area of the whole
picture currently being build by the BitImage BGI driver.
All requests to read or write outside the specified region
will be ignored. Functions reading pixel value from
outside of the specified region will always return zero
result (without error set).
DrawFunc - see PRT_PrintBGI.
UserPointer - see PRT_PrintBGI.
Initializes BITIMAGE BGI driver by calling PRT_initgraph. Calls
DrawFunc and DOES NOT close down BITIMAGE BGI driver (and does not free
the buffer with created bit image map). This should result in built
(x1,y1,x2,y2) rectangle of bit image map cut from the entire picture.
This function assumes that PRT buffer large enough to contain
(x1,y1),(x2,y2) rectangle was already allocated using PRT_AllocateBuffer
function.
Returns 0 on success, nonzero on failure.
PRT_closegraph
===============
int PRT_closegraph(void);
Function PRT_closegraph: integer;
Closes down the BGI driver which was being used to print the picture out.
In the case of BitImage BGI driver being used this function DOES NOT free
the buffer with created bit image map of the picture. Just you may close
down the BitImage BGI driver and still have buffer with created bit image
map of the picture. It enables you to activate any other BGI driver and
display created pixel map. But remember to free later the buffer calling
PRT_FreeBuffer function.
Returns 0 on success, nonzero on failure.
PRT_DriverName
===============
int PRT_DriverName ( unsigned driverno, char FAR * FAR* name_ptr );
Function PRT_DriverName ( driverno: word; var name_ptr: StringPtr ): integer;
Assigns to StringPtr pointer pointing to static string containing the name
of driver numbered driverno. The driver name is general name of all printers
supported by the driver or the name of the most common printer from
all supported by it. It can be used to list user all allowable printers and
let him choose the appropriate one.
Returns 0 on success, nonzero on failure.
PRT_DriverNo
=============
int PRT_DriverNo ( void );
Function PRT_DriverNo: integer;
Returns current driver number as set by PRT_SetDriver or minus one.
PRT_EMSBuffer
=============
int FAR_PROC pascal PRT_EMSBuffer ( int handle, long size, int usable )
Function PRT_EMSBuffer ( handle: integer; size: longint; usable: integer ):
integer;
Defines EMS buffer for use by the PrintBGI package.
Parameters:
usable : 0 (zero) means not to use EMS memory. Other arguments are
in that case ignored (but preferably should also be zero).
handle : Number of EMM handle to use for the buffer or zero (buffer
will be allocated by the package)
size : If handle is nonzero defines amount of memory (in bytes)
allocated to that handler by the caller.
If handle is zero then
- positive value defines maximum number of memory (which
will be rounded down to 16 KB boundary) that can be
used for the buffer by PrintBGI package.
- negative value defines minimum number of memory left
free after buffer allocation.
- zero allows to allocate as much memory as needed for
the buffer leaving only absolutely minimum free.
See also PRT_Buffer,PRT_XMSBuffer.
PRT_EndPrt
==========
int FAR_PROC _PRT__pascal PRT_EndPrt ( int handle );
Function PRT_EndPrt ( var handle: file ): integer;
Sends printer ending sequence to the specified handle.
To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
Note also that my standard PRT_Write function will call PRT_WriteError
function (set by PRT_SetErrorFunc) whenever output error occurs.
Returns 0 on success, nonzero on failure.
See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
PRT_SetErrorFunc.
PRT_grapherrormsg
============
char far * FAR_PROC PRT_grapherrormsg ( int errorcode );
Function PRT_grapherrormsg ( errorcode: integer ): string;
Returns pointer to error message associated with errorcode.
PRT_FreeBuffer
==============
int PRT_FreeBuffer (void);
Function PRT_FreeBuffer: integer;
Internal procedure freeing the buffer allocated by PRT_AllocateBuffer.
In the case of freeing EMS buffer does not restore EMS mapping to the state
from before PRT_AllocateBuffer. Thus you must be very careful if your
program uses also EMS memory.
Returns 0 on success, nonzero on failure.
PRT_getpixel
=============
int PRT_getpixel ( int x, int y );
Function PRT_getpixel ( x,y: integer );
Performs the same function as standard Borland getpixel function but with
two differences.
Parameters x and y are not whole picture relative
but buffer relative. It makes no difference if there is enough memory
for the whole picture. But if there is not enough free memory
PRT_getpixel(0,0) will return value of first pixel in the buffer
not the first pixel on the virtual screen. What this pixel is at the whole
picture depends on parameters x1 and y1 passed to PRT_SetViewSize.
The second difference is that if you load ( or link in) the driver
manually you will be able to call this function after closing BITIMAGE BGI
driver (after PRT_closegraph and maybe also after activating another BGI
driver) but, of course before releasing the screen buffer, and unregistering
the driver (see PRT_Unregisterfarbgidriver). If the driver is loaded
automatically (e.g. by PRT_initgraph) it will be deleted by PRT_closegraph
and you MUST NOT use this function in that case when BGI driver is not
active.
PRT_initgraph
==============
int FAR_PROC pascal PRT_initgraph( int far * graphdriver, int far *graphmode,
const char far *pathtodriver );
Function PRT_initgraph ( var graphdriver,graphmode: integer;
pathtodriver: string ): integer;
Parameters
*graphdriver : an integer that specifies graphic driver to be used.
Note that earlier you should install BGI driver
(currently BitImage driver only is included into the
package) using PRT_installuserdriver function.
If you specify DETECT as a passing argument value
then the driver last used in PRT_initgraph or last installed
using PRT_installuserdriver will be used. If none BGI printer
driver was installed so far than PRT_installuserdriver will
be called to install appropriate driver for printer defined
by PRT_SetDriver. No true auto detection is (or will be)
available.
*graphmode : an integer that specifies graphic mode to be used.
It should be zero value since in current version you
must specify desired printing mode using PRT_SetDriver
function.
pathtodriver : Specifies path to BGI drivers and CHR fonts. This parameter
will be passed further to standard initgraph routine.
Initializes BITIMAGE BGI driver for creating bit image map.
Note that YOU MUST earlier specify rectangular area for which bit map will
be created by calling PRT_SetViewSize function.
All requests for drawing (or reading) pixels outside that
area will be ignored without any error codes. This would enable
building the screen from rectangular pieces and printing it out even if
there is not enough free memory to build the whole bit image map of
printed picture at once.
You must call PRT_SetViewSize before PRT_initgraph.
(x1,y1),(x2,y2) area (specified by PRT_SetViewSize) must fill
entirely within - PREVIOUSLY - allocated buffer (via PRT_AllocateBuffer),
otherwise an error code is return.
Returns 0 on success, nonzero on failure.
PRT_InitPrt
============
int FAR_PROC _PRT__pascal PRT_InitPrt ( int handle );
Function PRT_InitPrt ( var handle: file ): file;
Sends printer initialization sequence to the specified handle.
To print it out uses PRT_write function set by PRT_SetWriteFunc routine.
Note also that my standard PRT_Write function will call PRT_WriteError
function (set by PRT_SetErrorFunc) whenever output error occurs.
Returns 0 on success, nonzero on failure.
See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
PRT_SetErrorFunc.
PRT_installuserdriver
=====================
int FAR_PROC pascal PRT_installuserdriver ( const char far * name,
int huge (*detect)(void) );
Type DetectFunc = function: integer;
PRT_installuserdriver ( name: string; detect: DetectFunc ): integer;
Used instead of standard Turbo installuserdriver function. You should
use it to install BitImage BGI driver.
PRT_MaxDriver
==============
int PRT_MaxDriver ( void );
Function PRT_MaxDriver : integer;
Returns maximum allowed printer driver number in PRINTBGI package;
See also PRT_SetDriver, PRT_DriverName, PRT_DriverNo.
PRT_MaxMode
============
int PRT_MaxMode ( unsigned driverno, int FAR *maxmode );
Function PRT_MaxMode ( printerno: word; var maxmode: integer ): integer;
Assigns to maxmode maximum mode number allowed for given driverno.
Returns 0 on success, nonzero on failure.
See also PRT_ModeName, PRT_ModeNo.
PRT_ModeName
=============
int PRT_ModeName ( unsigned driverno, int modeno,
char FAR* FAR* name_ptr );
Function PRT_ModeName ( driverno: word; modeno: integer;
var name_ptr: StringPtr ): integer;
Assigns to StringPtr pointer pointing to static string containing name
of mode modeno and printer numbered driverno. It can be used to list user
all allowable modes and let him choose one.
Returns 0 on success, nonzero on failure.
PRT_ModeNo
==========
int PRT_ModeNo ( void );
Function PRT_ModeNo: integer;
Returns current mode number as set by PRT_SetDriver or negative
value.
PRT_PrintBGI
=============
int far PRT_PrintBGI ( int far * graphdriver, int far *graphmode,
const char far *pathtodriver,
int ( FAR_PTR * FAR_PROC /* pascal */ Draw)
(void far* UserPointer),
void far* UserPointer );
Type DrawType = function DrawFunc(UserPointer: pointer): integer;
Function PRT_PrintBGI ( var graphdriver,graphmode: integer;
pathtodriver: string;
DrawFunc : DrawType,
UserPointer: pointer );
Parameters
graphdriver,graphmode,pathtodriver - see PRT_initgraph.
Draw : function drawing picture you want to print.
UserPointer : This parameter is not used by my library routines
and will be passed unchanged to your Draw function.
It may point to list of parameters for your Draw
function.
This is the main function of the whole package. In fact it does most
of the work and using it is the most recommended way to use the whole
PRINTBGI package. Of course in some nonstandard situations you may
want to use some lower level routines to get more control over the package.
But I think it will be very rarely case.
I'll list all functions it does in the order they are performed.
It should let you better understand other functions of this
package.
So it does the following.
1. Checks the correctness of arguments used in call to
PRT_SetDriver. Returns immediately PRT_NOT_INITIALIZED value if
they are incorrect, otherwise goes to step 2.
2. Checks if any BGI driver was active when it was called. If it
was then closes it down and saves information needed to restore
screen graphic mode. Note that this step (or step 7
restoring caller graphic mode) may not work correctly at all
circumstances (since for example it is very hardly to guess
what BGI driver was active at call to PRINTBGI).
So I highly recommend you to close down any BGI drivers you
were using before calling this function. Note also that
rectorecrtmode function DOES NOT close down BGI driver but
only deactivates it. So you MUST USE closegraph function rather
than rectorecrtmode before calling PRT_PrintBGI.
3. Allocates buffer using PRT_AllocateBuffer function.
If buffer allocation is unsuccessful returns immediately, otherwise
computes window size filling entirely in the allocated buffer
and calls PRT_SetViewSize to set it. This window may (or may not)
cover the whole printing picture.
4. Calls PRT_Open and PRT_InitPrt to open file handle and to send
initialization codes to the printer.
5. Calls PRT_BuildBitMap to create bit image map of current
rectangular piece of picture wich fits into allocated buffer.
PRT_BuildBitMap is described earlier in this chapter.
6. Calls PRT_PrintBuffer to print out current buffer ( which now
contains one piece of picture). If it is not the last
(or the only one) piece to print returns to point 5.
7. Calls PRT_EndPrt and PRT_Close;
8. Calls PRT_closegraph to close down the BGI driver used to create
bit image map of the printed picture.
9. Frees allocated buffer by calling PRT_FreeBuffer.
10. If in step 2 the active BGI driver was closed down tries now to
reactivate it. Note that it uses standard detectgraph function to
determine which BGI driver reactivate. So if you had nonstandard
BGI drivers active (e.g. SVGA or VGA256) it may happen that standard
VGA driver will be reactivate instead of the actually active one.
To avoid this problem either close down video BGI driver (using
closegraph) before calling PRT_PrintBGI or install nonstandard
BGI drivers with appropriate auto detection function
(see installuserdriver function in Borland documentation).
Note also that screen image is not restored.
11. Returns to the caller.
Function DrawFunc passed as an argument should meet the following
conditions.
- It draws on the screen the picture you want to print.
- It does not use any nonstandard graphic procedures (that is not
defined in GRAPH.TPU or GRAPHICS.LIB) to manipulate screen
output.
- It does not use initgraph, restorecrtmode, closegraph or setgraphmode
procedure. It simply assumes that appropriate graphic mode was
established before calling it.
- It is written in BGI independent way. That is it uses getmaxx,
getmaxy, getmaxcolor, getaspectratio to get device dependent
characteristic and scales all output according to it.
- Although it is not necessary it is recommended that it draws
the same picture (if the same BGI driver is used) each time
it is called.
This may be because if there is not enough memory to build bit image
map of the entire picture at once it is necessary to call
DrawFunc routine few times to create the picture piece by
piece (lines by lines). If it would draw different output at
consecutive calls then printed lines would not suit each other.
- It returns zero on success and nonzero on failure. This nonzero code
will cause immediate finish of the PRT_PrintBGI function and will
be also returned by it to the caller.
Note also that if there is not enough free memory to build the whole
bit image map at once then some graphic functions which read the
screen explicitly (e.g. getpixel,getimage) or implicitly (e.g. floodfill) may
produce inaccurate results. This may happen if they refer to currently
not building part of the picture.
Setting PRT_HaltPrinting variable to nonzero value lets you break
this function before it will finish.
PRT_PrintBuffer
================
typedef int* PRT__handleT;
int PRT_PrintBuffer (PRT__handleT handle);
Function PRT_PrintBuffer(var handle: file): integer;
Prints entire "screen" buffer to the specified handle
adding necessary control codes (see PRT_SetDriver).
To print out the buffer it uses PRT_Write function set by
PRT_SetWriteFunc routine.
Note also that my standard PRT_Write function will call PRT_WriteError
function (set by PRT_SetErrorFunc) whenever output error occurs.
Returns 0 on success, nonzero on failure.
See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetWriteFunc,
PRT_SetErrorFunc.
PRT_registerfarbgidriver
========================
int FAR_PROC pascal PRT_registerfarbgidriver ( void far pascal
(*driver)(void) );
Type DriverProc = procedure;
PRT_registerbgidriver ( driver: DriverProc ): integer;
To register BGI driver from the package use PRT_registerfarbgidriver
instead of standard registerbgidriver or registerfarbgidriver function.
But note that before deleting registered driver from memory you
MUST use PRT_Unregisterfarbgidriver function.
PRT_RescaleFillPattern
=======================
int PRT_RescaleFillPattern ( int r );
Function PRT_RescaleFillPattern ( r: integer ): integer;
Since external graphic devices have in most cases grater maximum
possible resolution than screens, standard 8x8 fill patterns seem to be
too small to use. This procedure let you demand of rescaling standard
8x8 fill patterns to 16x16 ones.
Parameter r means
0 = never rescale to 16x16,
1 = always rescale to 16x16,
-1 = rescale to 16x16 at high densities only.
The default value is -1.
Returns 0 on success, nonzero on failure.
If used must be called before initializing BITIMAGE BGI driver.
See also setfillpattern16.
PRT_Resolution
===============
int PRT_Resolution ( int FAR *Xres, int FAR *Yres );
Function PRT_Resolution ( var Xres,Yres : integer ): integer;
Assigns to Xres and Yres dpi (dots per inch) resolution in
appropriate direction according to last call of PRT_SetDriver.
Returns 0 on success, nonzero on failure.
PRT_Send
========
int pascal PRT_Send( const void far *p, unsigned slen);
Function PRT_Send( p: string): integer;
Calls PRT_Open, PRT_Write, PRT_Close to send slen bytes
pointed to by p to the output file of a name set by PRT_SetOutName.
Returns zero om success, nonzero on failure.
See also PRT_SetOutName, PRT_Open, PRT_Write, PRT_Close.
PRT_SetBuffer
==============
int PRT_SetBuffer ( long size, unsigned BufOpt );
Function PRT_SetBuffer ( size : longint; BufOpt: word ): integer;
Parameters
BufOpt : specifies what kind of memory may be used for buffer.
Allowed values.
NotUseEMS (1) - use XMS or conventional memory
NotUseXMS (2) - use EMS or conventional memory.
NotUseEMS+NotUseXMS - use conventional memory only.
0 - use any memory.
size : if positive specifies maximum amount of memory that
can be used for the buffer.
If negative specifies how minimum amount of memory that
must be left free after buffer allocation.
This parameter is currently meaningful only if conventional
memory is used.
Returns
0 on success, nonzero on failure.
PRINTBGI package uses the so called screen buffer to build bit
image map of printing output in it. This procedure specifies what kind
of memory can be used for that buffer. The whole buffer is allocated
in one kind of memory in the following priority order XMS, EMS,
conventional memory.
If you have no particular need you should not call this procedure.
If not called PRINTBGI will behave as you call it with both parameters
zeroed thus enabling allocation of the buffer of the best size.
If you let PRINTBGI to use EMS memory then keep in mind that DrawFunc
(set as parameter to PRT_PrintBGI) or any procedure called by it may not use
EMS memory.
Note also that PRINTBGI does not save and restore EMS mapping at
any time. So if you want you can save EMS mapping before call of any
function that uses it and restore it afterwards. Following functions
may change EMS mapping: PRT_PrintBuffer, PRT_PrintBGI, PRT_BuildBitMap,
PRT_getpixel as well as any graphic routines using BitImage BGI driver.
If used, must be called before initializing BITIMAGE BGI driver.
Try to use PRT_Buffer, PRT_EMSBuffer or PRT_XMSBuffer instead.
PRT_SetCloseFunc
=====================
typedef int ( FAR_PROC * PRT_CloseFuncP)( int* handle );
PRT_CloseFuncP PRT_SetCloseFunc ( int far f(int* handle) );
Type CloseFuncType = Function(var handle:file): integer;
Function PRT_SetCloseFunc ( f: CloseFuncType ): CloseFuncType;
Defines function (passed as an argument f) which will be called to close
file handle used to print out the picture. The f function takes an integer*
argument which is supposed to contain an opened file handle. Exactly this is
the case if you do not specified your own open function. if you specified
your own open function the argument passed to close f function
contains a number returned from your open function (see PRT_SetOpenFunc).
This f function should return zero on success and suitable nonzero code
otherwise.
If NULL is passed as an argument f then the old close function used so far
will not be changed.
PRT_SetCloseFunc returns pointer to previously used close function.
See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.
PRT_SetDriver
==============
int PRT_SetDriver ( unsigned drv, unsigned mode,
unsigned width, unsigned height, unsigned options );
Function PRT_SetDriver ( drv,mode : word; width,height : word;
options: word ) : integer;
Parameters
drv : defines driver (and thus printer) number which will be
used. Allowed values (See PRINTBGI.H or PRINTBGI.INT) are:
IBM9, EPSON9, PANASONIC9, EPSON24, IBM24, HPLJII, HPPaintJet,
LaserJet, PaintJet, IBM9c, EPSON9c, EPSON24c, IBM24c.
mode : defines driver (printer) mode number which will be
used. Allowed values are defined in PRINTBGI.H
(or PRINTBGI.INT for pascal version).
width,height : defines width and height of the next printing
picture in 1/1000 inch values. That is 4000
means 4 inches.
options : can be defined as zero or it may have set one of the
following bits
PRT_ROTATE : if not set picture will be printed horizontally
if set picture will be printed vertically.
PRT_INVERSE : if not set pixel of value 0 will be printed
as black and pixel of value 1 will be printed white.
1 means otherwise.
For color printers 1 will force bit negation
of pixel value before printing.
Returns
0 on success, nonzero on failure.
Default values.
Must be called. No default values assumed.
Values defined by PRT_SetDriver stay in effect until next call of
that procedure changing them explicitly.
Must be called before initializing BITIMAGE BGI driver.
No checking is (or will be) made if specified values are correct for your
hardware. It is responsibility of the caller to detect hardware (or rather
ask user to define it) and specify picture size acceptable by it.
PRT_SetErrorFunc
=====================
typedef int ( FAR_PROC * PRT_ErrorFuncP) ( int* handle );
PRT_ErrorFuncP PRT_SetErrorFunc ( int WrErrFunc(int* handle) );
Type ErrFuncType = Function ( var handle: file ): integer;
Function PRT_SetErrorFunc ( ErrFunc: ErrFuncType ): ErrFuncType;
Defines function (passed as an argument ErrFunc) which will be
called whenever I/O error occur during printing. ErrFunc must
return zero to retry printing or nonzero error code to abort
printing. In the second case the function in which an error occurred
returns immediately to the caller with the same return code as received
from ErrorFunc.
If ErrFunc argument passed is NULL no ErrFunc will be called
whenever I/O error occurs.
PRT_SetErrorFunc returns pointer to currently used ErrFunc.
PRT_SetMargins
===============
int PRT_SetMargins ( int left, int top );
Function PRT_SetMargins ( left,top : integer ) : integer;
Specifies (in 1/1000 inch) the left and top margins that should be
left free during printing. Note that in most cases real margins left will
be only some approximation of the specified values and may considerably
differ from them.
Returns 0 on success, nonzero on failure.
PRT_SetOpenFunc
=====================
typedef int* ( FAR_PROC * PRT_OpenFuncP)( void );
PRT_OpenFuncP PRT_SetOpenFunc ( int* far f(void) );
Type PRT__FilePtr = ^file;
Type OpenFuncType = Function: PRT__FilePtr;
Function PRT_SetOpenFunc ( f: OpenFuncType ): OpenFuncType;
Defines function (passed as an argument f) which will be called to open
file handle for printing out the picture. The f function takes no arguments
and should return opened file handle. Returning nonpositive value will be
treated as an error.
If NULL is passed as an argument f then the old open function used so far
will not be changed.
PRT_SetOpenFunc returns pointer to previously used open function.
See also PRT_SetCloseFunc, PRT_SetWriteFunc, PRT_SetErrorFunc.
PRT_SetOutName
==================
int PRT_SetOutName ( const char FAR * DeviceName );
Function PRT_SetOutName ( DeviceName : string );
Specifies where the graphic output should be sent. DeviceName
can be any valid DOS device name (such as PRN,LPT1,LPT2,COM1, etc.)
or file name (with or without the path). It is used in pascal assign
procedure or C open function. Note that string pointed to by DeviceName
is not copied but only reference is remembered. So DeviceName should
not point to local dynamic area but to STATIC one rather.
Returns 0 on success, nonzero on failure.
PRT_SetViewSize
===============
int FAR_PROC pascal PRT_SetViewSize( int x1, int y1, int x2, int y2 );
Function PRT_SetViewSize( x1,y1, x2,y2: integer ): integer;
Parameters
x1,y1,x2,y2 - specifies rectangular piece of picture which will be
built by the BitImage BGI driver.
See also PRT_initgraph.
PRT_SetWriteFunc
=====================
typedef int ( FAR_PROC * PRT_WriteFuncP)
( int* handle, const void FAR_PTR * b, unsigned len );
PRT_WriteFuncP FAR_PROC pascal PRT_SetWriteFunc
( int far f(int* handle,void FAR_PTR* buf,
unsigned len) );
Type WriteFuncType = Function(var handle:file; var b; len: word ): integer;
Function PRT_SetWriteFunc ( f: WriteFuncType ): WriteFuncType;
Defines function (passed as an argument f) which will be called to print
out len bytes pointed to by buf pointer.
Parameters of f function
handle : an integer number returned by an open function set by
PRT_SetOpenFunc. My default open function simply returns
file handle.
buf : Pointer to data bytes which must be printed out.
len : Number of bytes to print.
If function f returns nonzero value it will be treated as an I/O error.
If NULL is passed as an argument f then the old write function used so far
will be not changed.
PRT_SetWriteFunc returns pointer to previously used write function.
See also PRT_SetOpenFunc, PRT_SetCloseFunc, PRT_SetErrorFunc.
PRT_Unregisterfarbgidriver
========================
int FAR_PROC pascal PRT_Unregisterfarbgidriver ( void far pascal
(*driver)(void) );
Type DriverProc = procedure;
PRT_Unregisterfarbgidriver ( driver: DriverProc ): integer;
Used to unregister driver installed with PRT_registerfarbgidriver function.
You MUST use it before erasing registered BitImage driver from memory.
PRT_XMSBuffer
=============
int FAR_PROC pascal PRT_XMSBuffer ( int handle, long size, int usable )
Function PRT_XMSBuffer ( handle: integer; size: longint; usable: integer ):
integer;
Defines XMS buffer for use by the PrintBGI package.
Parameters:
usable : 0 (zero) means not to use XMS memory. Other arguments are
in that case ignored (but preferably should also be zero).
handle : Number of XMM handle to use for the buffer or zero (buffer
will be allocated by the package)
size : If handle is nonzero defines amount of memory (in bytes)
allocated to that handle by the caller.
If handle is zero then
- positive value defines maximum number of memory (which
will be rounded down to 16 KB boundary) that can be
used for the buffer by PrintBGI package.
- negative value defines minimum number of memory left
free after buffer allocation.
- zero allows to allocate as much memory as needed for
the buffer leaving only absolutely minimum free.
Note that XMS buffer requires also some conventional memory buffer to
be allocated.
See also PRT_Buffer,PRT_EMSBuffer.
PRT_XMSBufferNeeded
=================
long PRT_XMSBufferNeeded ( int x1, int y1, int x2, int y2 );
Function PRT_XMSBufferNeeded ( x1,y1,x2,y2: integer ): longint;
Returns size of buffer needed to draw picture in XMS memory of specified
size and on printer set by PRT_SetDriver. The returned value will be somewhat
larger than that from PRT_BufferNeeded. If there exist less free memory than
needed then picture would be drawn in pieces. In that case results of all
procedures reading pixel values may be inaccurate.
May be called only after PRT_SetDriver.
See also PRT_BufferNeeded.
setcharsize_Pix
===============
void setcharsize_Pix (int width, int height);
Procedure setcharsize_Pix ( width,height: integer );
Sets char size width and heigth. The parameters should be given
in pixels. You may use it to obtain text proportional to the picture
sizes. For example if you want text height to be 1/60 of the whole
picture height and width 1/80 of the whole picture width you may use
following statement (in C language)
setcharsize_Pix ( getmaxx()/80, getmaxy()/60 );
setfillpattern16
=================
void setfillpattern16 ( char FAR * upattern, int color );
Procedure SetFillPattern16 ( upattern: FillPatternType; color: word );
If standard 8x8 fill patterns are not satisfied for you use this
function to define 16x16 patterns. Note that calling this function take
effect only when BITIMAGE BGI driver is active, for all other BGI drivers it
will be ignored. So the best approach is probably calling standard
setfillpattern function and then setfillpattern16. In that case ignoring
setfillpattern16 will cause that the pattern set by standard setfillpattern
function will be still in effect.
PRT_HaltPrinting
================
Global variable. It ss set to zero when PRT_PrintBGI starts. You may set it
to nonzero value to force almost immediate return from PRT_PrintBGI function
(without ending printing). This variable is tested after each line printed.
Note however that if PRT_PrintBGI called your Draw function then it will wait
for the Draw function to end before testing PRT_HaltPrinting.
========================================================================
GRAPHIC FUNCTIONS
========================================================================
This section will describe all graphics functions that can be found
in Borland Graph.TPU unit for TP or GRAPHICS.LIB for B/TC(++). Note
that detailed description of each function can be found in appropriate
Borland documentation. Here are only given some differences from their
use in PRINTBGI package and standard Borland BGI drivers.
Following functions can be used with my BitImage BGI driver in the
same way as with standard Borland BGI drivers.
void far arc(int x, int y, int stangle, int endangle, int radius);
void far bar(int left, int top, int right, int bottom);
void far bar3d(int left, int top, int right, int bottom,
int depth, int topflag);
void far circle(int x, int y, int radius);
void far clearviewport(void);
void far drawpoly(int numpoints, int far *polypoints);
void far ellipse(int x, int y, int stangle, int endangle,
int xradius, int yradius);
void far fillellipse( int x, int y, int xradius, int yradius );
void far fillpoly(int numpoints, int far *polypoints);
void far getarccoords(struct arccoordstype far *arccoords);
void far getaspectratio(int far *xasp, int far *yasp);
int far getbkcolor(void);
int far getcolor(void);
void far getfillpattern(char far *pattern);
void far getfillsettings(struct fillsettingstype far *fillinfo);
int far getgraphmode(void);
void far getlinesettings(struct linesettingstype far *lineinfo);
int far getmaxcolor(void);
int far getmaxx(void);
int far getmaxy(void);
char * far getmodename( int mode_number );
void far getpalette(struct palettetype far *palette);
int far getpalettesize( void );
void far gettextsettings(struct textsettingstype far *texttypeinfo);
void far getviewsettings(struct viewporttype far *viewport);
int far getx(void);
int far gety(void);
void far graphdefaults(void);
char * far grapherrormsg(int errorcode);
void far _graphfreemem(void far *ptr, unsigned size);
void far * far _graphgetmem(unsigned size);
int far graphresult(void);
unsigned far imagesize(int left, int top, int right, int bottom);
int far installuserfont( char far *name );
void far line(int x1, int y1, int x2, int y2);
void far linerel(int dx, int dy);
void far lineto(int x, int y);
void far moverel(int dx, int dy);
void far moveto(int x, int y);
void far pieslice(int x, int y, int stangle, int endangle,
int radius);
void far putimage(int left, int top, void far *bitmap, int op);
void far putpixel(int x, int y, int color);
void far rectangle(int left, int top, int right, int bottom);
int registerbgifont (void (*font)(void));
int far registerfarbgifont (void far *font);
void far sector( int X, int Y, int StAngle, int EndAngle,
int XRadius, int YRadius );
void far setaspectratio( int xasp, int yasp );
void far setcolor(int color);
void far setfillpattern(char far *upattern, int color);
void far setfillstyle(int pattern, int color);
unsigned far setgraphbufsize(unsigned bufsize);
void far setlinestyle(int linestyle, unsigned upattern,
int thickness);
void far settextjustify(int horiz, int vert);
void far setusercharsize(int multx, int divx,
int multy, int divy);
void far setviewport(int left, int top, int right, int bottom,
int clip);
int far textheight(char far *textstring);
int far textwidth(char far *textstring);
Following functions may differ somewhat when used with printer
devices. See short descritption after function declaration.
void far cleardevice(void);
Does not enforce printing. Buffer is cleared and if mot printed
earlier its content is lost forever.
void far closegraph(void);
You rather shouldn't use it with BitImage BGI driver. Use PRT_closegraph
instead.
void far detectgraph(int far *graphdriver,int far *graphmode);
It will return detect values for screen not for external devices.
void far floodfill(int x, int y, int border);
Not implemented in current release. It'll be implemented in future
releases but remember that may produce some inaccurate results if
there is less memory than needed to build whole bit map for the
picture. Compare with PRT_PrintBGI description. Note also that it
cannot be implemented for some kind of output devices.
struct palettetype far * far getdefaultpalette( void );
Not implemented.
char * far getdrivername( void );
Returns BGI driver name. Since the package uses always the
same BGI driver (called BITIMAGE BGI driver) it will always return
the word BITIMAGE. To obtain names of printer drivers supported call
PRT_DriverName function described in earlier section.
void far getfillpattern(char far *pattern);
See also getfillpattern16 and PRT_RescaleFillPattern.
void far getimage( int left, int top, int right, int bottom,
void far *bitmap);
May not work if there is not enough memory for the entire picture.
Otherwise is fully supported.
int far getmaxmode(void);
You should use rather PRT_MaxMode instead. Currently it always
returns zero since BitImage BGI driver being used supports one mode
only. Parameters which configure the driver for your needs can be set
using PRT_SetDriver function.
int far getmaxx(void);
You should use it to rescale output according to screen sizes.
int far getmaxy(void);
You should use it to rescale output according to screen sizes.
void far getmoderange(int graphdriver, int far *lomode,
int far *himode);
Shouldn't be used.
unsigned far getpixel(int x, int y);
May not work if there is not enough memory for the entire picture.
Otherwise is fully supported.
char * far grapherrormsg(int errorcode);
You may use PRT_grapherrormsg instead.
void far initgraph(int far *graphdriver,
int far *graphmode,
char far *pathtodriver);
To initialize BitImage BGI driver you must use PRT_initgraph instead.
int far installuserdriver( char far *name, int huge (*detect)(void) );
You must use PRT_installuserdriver to install PRINTBGI drivers.
void far outtext(char far *textstring);
To print standard fonts of code 128 or higher you should use DOS
GrafTabl command before, otherwise printing is garbage. Note also
that fonts table for characters 127 or lower is taken from ROM BIOS.
If you have no such a table in standard place some problems may also
occur.
See also settextstyle comments.
void far outtextxy(int x, int y, char far *textstring);
See outtext and settextstyle comments.
int registerbgidriver (void (*driver)(void));
To register BitImage driver you should use PRT_registerfarbgidriver
instead.
int far registerfarbgidriver (void far *driver);
To register BitImage driver you should use PRT_registerfarbgidriver
instead.
void far restorecrtmode(void);
Shouldn't be used. Before using PrintBGI toolkit functions you must
close down any active video BGI driver. To do this use closegraph not
restorecrtmode function. On the other hand using restorecrtmode with
BitImage BGI driver has little sense.
void far setactivepage(int page);
Not implemented.
void far setallpalette(struct palettetype far *palette);
Not implemented.
void far setaspectratio( int xasp, int yasp );
You may use it to change current aspect ratio but remember that
default values are correct.
void far setbkcolor(int color);
Not implemented in current release.
void far setfillpattern(char far *upattern, int color);
See setfillpattern16 and PRT_RescaleFillPattern in previous section.
void far setfillstyle(int pattern, int color);
See PRT_RescaleFillPattern in previous section.
void far setgraphmode(int mode);
Shouldn't be used.
void far setpalette(int colornum, int color);
Not implemented.
void far setrgbpalette(int colornum,
int red, int green, int blue);
Not implemented.
void far settextstyle(int font, int direction, int charsize);
May produce different results for standard fonts (DEFAULT_FONT)
and direction other than HORIZ_DIR or VERT_DIR. May also behave
slightly different when text expands beyond clip region. You may use
setcharsize_Pix function to set font size in pixels.
void far setvisualpage(int page);
Not implemented.
void far setwritemode( int mode );
In difference with Borland's BGI drivers write mode defined by
that procedure is valid for all subsequent write operations. Mode
argument may be one of the following: COPYPUT, XORPUR, ORPUT,
AND_PUT, NOT_PUT not just limited to fist two constants only (as is
in Borland's library).
DEFINING YOUR OWN PRINTERS
==========================
Printers descriptions used by the package are contained in Drivers
module. I included in this package all files necessary to compile
Drivers.ASM. So you may modify this file and compile it creating OBJ file
which in turn you should added to PRTGRAPH.LIB replacing old OBJect member
of the same name. Turbo Pascal users should compile Drivers.Pas file
instead of modifying PRTGRAPH.LIB.
I must tell you that defining your own printer is not easy. You probably
will have a lot of troubles with it unless you are an expert in using
printers in graphic mode. In that case you should not have troubles. Read
Drivers.INC and then copy one of the closest printer already defined in
Drivers.ASM and modify parameters you need.
I suppose there are some printers which cannot be added this way. If you
have such a one it means that it requires the modification of printers
definitions structure as well as some other source code modifications.
Please contact the author in that case.
THE FUTURE
==========
If there is some interest in this package I will write 1.0 version
which will
- support all dot matrix printers, postscript printers and some
others as well as some plotters,
- contain table (and function to use it) with names of all available
printers and appropriate driver number used by the package (if users
support me in doing it) ,
- let you keep printers definitions in separate file or linked it with
the main module,
- work in all memory models (except tiny of course),
- be tested on more printers,
- contain some more improvements, I hope.
All registered users will obtain this 1.0 version completely free.
To contact the author write to
Andrzej Resztak
ul. K. Wallenroda 2c/18
20-607 Lublin
POLAND
or (preferably) to e-mail address:
Resztak@PLUMCS11.bitnet
/* end of PRINTBGI.DOC */